feat: add withAlternative alias mechanism for CometConf#4979
Merged
Conversation
…ceSortMergeJoin Introduces `.withAlternative(oldKey, ...)` on `ConfigBuilder`. Reads check the primary key first, then any registered alternatives in order; reading a value from an alternative logs a one-time deprecation warning per JVM naming the current key. Threaded through `TypedConfigBuilder` into `ConfigEntryWithDefault` and `OptionalConfigEntry` so the same mechanism covers configs with defaults, env-var overrides, and optional configs. Pilots the mechanism by renaming `spark.comet.exec.replaceSortMergeJoin` to `spark.comet.exec.forceShuffleHashJoin.enabled` (Scala symbol `COMET_FORCE_SHJ`), keeping the old key working as an alias. Adds `CometConfSuite` with tests for primary-wins, alternative fallback, default, multiple alternatives, OptionalConfigEntry, and type conversion through the alias path. Adds a Configuration Conventions contributor-guide page that documents the key/symbol naming rules and the rename workflow. Broader rename backlog tracked in apache#4978, per the 1.0.0 tracker apache#4082.
…ffix Rename correction: use the past-participle form matching Spark's `ShuffledHashJoin` class. Also drops the `.enabled` suffix — the `force` verb already encodes the boolean action, so `.enabled` is redundant for this key. Softens the Configuration Conventions doc's boolean-suffix rule accordingly: descriptor-form flags (debug.enabled, metrics.enabled) still end in `.enabled`; action-verb flags (force..., allow...) can omit it.
andygrove
commented
Jul 20, 2026
Comment on lines
+375
to
+377
| val COMET_FORCE_SHJ: ConfigEntry[Boolean] = | ||
| conf(s"$COMET_EXEC_CONFIG_PREFIX.forceShuffledHashJoin") | ||
| .withAlternative(s"$COMET_EXEC_CONFIG_PREFIX.replaceSortMergeJoin") |
Member
Author
There was a problem hiding this comment.
This is an example of renaming a config and preserving the old deprecated name
Contributor
There was a problem hiding this comment.
Should we mention that replaceSortMergeJoin is deprecated somewhere?
kazuyukitanimura
approved these changes
Jul 20, 2026
Comment on lines
+375
to
+377
| val COMET_FORCE_SHJ: ConfigEntry[Boolean] = | ||
| conf(s"$COMET_EXEC_CONFIG_PREFIX.forceShuffledHashJoin") | ||
| .withAlternative(s"$COMET_EXEC_CONFIG_PREFIX.replaceSortMergeJoin") |
Contributor
There was a problem hiding this comment.
Should we mention that replaceSortMergeJoin is deprecated somewhere?
Member
Author
|
@kazuyukitanimura since CI is already running, I'll follow up with a docs PR for the one renamed config |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Kicks off the "Review all configuration options and consider renaming some for consistency" item on the 1.0.0 tracker (#4082). This PR lands the machinery + first rename, and files #4978 to track the full rename backlog.
.withAlternative(oldKey, ...)toConfigBuilder. Reads check the primary key first, then any registered alternatives in order. Reading a value from an alternative logs a one-time deprecation warning per JVM per alternative key, naming the current key.TypedConfigBuilder→ConfigEntryWithDefaultandOptionalConfigEntry, so configs with defaults, env-var overrides, and optional configs all support aliases.spark.comet.exec.replaceSortMergeJoin→spark.comet.exec.forceShuffleHashJoin.enabled(Scala symbolCOMET_REPLACE_SMJ→COMET_FORCE_SHJ). Old key still works as a deprecated alias.docs/source/contributor-guide/documenting key/symbol naming rules and the rename workflow.CometConfSuitecovers primary-wins, alternative fallback, default, multiple alternatives,OptionalConfigEntry, type conversion through the alias, and the pilot rename end-to-end.Related:
Test plan
./mvnw -pl spark test -Dtest=none -Dsuites="org.apache.comet.CometConfSuite"— 7 tests pass locally./mvnw -pl spark -am compile -DskipTests— cleannpx prettier "**/*.md" --write— clean